Skip to content

feat(protocol): specify the rpc.dig.net dual-mode gateway + ephemeral read certs#10

Merged
MichaelTaylor3d merged 1 commit into
mainfrom
docs/dual-transport-rpc-18
Jul 4, 2026
Merged

feat(protocol): specify the rpc.dig.net dual-mode gateway + ephemeral read certs#10
MichaelTaylor3d merged 1 commit into
mainfrom
docs/dual-transport-rpc-18

Conversation

@MichaelTaylor3d

Copy link
Copy Markdown
Contributor

Summary

Super-repo Issue DIG-Network/dig_ecosystem#18 (DESIGN-FIRST: dual-transport RPC scheme). The peer-network spec already normatively defined the two RPC tiers (§0 mTLS PEER/CONTROL vs anonymous PUBLIC-READ) and the tier map (§7a), but it treated rpc.dig.net as purely the anonymous public-read front. That leaves an unresolved question for a protocol implementer: how does a node-class client (the digstore CLI, dig-sdk, any DIG-identity-key holder) read/write against the public gateway without downgrading to the anonymous path — and can an anonymous browser get any stronger channel binding than plain HTTPS?

This PR adds the missing normative design, scoped entirely to docs.dig.net:

  • New docs/protocol/peer-network.md §0a ("rpc.dig.net is dual-mode"): the gateway answers on two independently-authenticated fronts — an mTLS front (CERT_REQUIRED) for node-class clients (their identity-derived cert, used at all three tiers of the client→node ladder: dig.locallocalhostrpc.dig.net) and the existing plain-HTTPS+CORS-* front for browsers.
  • Ephemeral self-signed client certificate flow: an anonymous reader MAY instead dial the mTLS front with a throwaway, unregistered certificate purely to complete the CERT_REQUIRED handshake, getting a TLS-session-bound (replay-resistant) read with no persisted identity, reputation, or authorization implied.
  • Boundary invariant preserved explicitly: reaching the mTLS front never grants a peer/write/config method to an anonymous caller — enforced by what the request names, not which front carried it.
  • Design-status callout: implementations gate on the gateway mTLS endpoint's existence and must not hard-break before it is deployed (today rpc.dig.net only serves the plain-HTTPS front).
  • Cross-referenced from dig-rpc.md's public-read-tier tip, the §7a tier-map notes, the §11 conformance table, and a new Related link to run-a-node/point-a-consumer.md (the task-oriented ladder page, unchanged — this PR only touches the protocol-developer spec).
  • static/knowledge-graph.json regenerated (npm run gen) to pick up the new cross-link edge.

Verified

  • npm run build — all 15 locale builds succeed with onBrokenLinks/onBrokenAnchors: "throw" (every new anchor/cross-link resolves); llms.txt/sitemap.xml/robots.txt present in dist/.
  • npm run typecheck — clean.
  • npm run test:unit — passing.
  • npm run test:a11y (axe + ARIA snapshot + keyboard-nav + mobile-nav) — 22/22 passing.
  • npm run test:e2e (full suite incl. SEO/hreflang meta) — 28/28 passing.

Version bump

Minor (0.2.00.3.0) — purely additive normative spec content (new section, new cross-links); no existing section removed, renumbered, or changed in meaning.

Test plan

  • CI deploy.yml test job green (build + a11y/SEO)
  • commitlint — Conventional Commit format
  • ensure-version-incrementpackage.json version increased

… read certs

The peer-network spec already had the two RPC tiers (mTLS peer/control vs
anonymous public-read) but treated rpc.dig.net as purely the anonymous
front. Node-class clients (digstore CLI, dig-sdk, any DIG-identity-key
holder) must never downgrade to that anonymous path, even at the public
gateway, per the client->node connection order contract.

- New peer-network.md §0a: rpc.dig.net is dual-mode — an mTLS front
  (CERT_REQUIRED) for node-class-client identity certs, reached at all
  three ladder tiers (dig.local/localhost/rpc.dig.net), alongside the
  existing plain-HTTPS+CORS front for browsers.
- Ephemeral self-signed client certificate flow: an anonymous reader may
  use the mTLS front for channel-bound request integrity without any
  persisted identity or reputation, binding a signed request to its TLS
  session.
- Design-status note: implementations gate on the gateway mTLS endpoint's
  existence and must not hard-break before it is deployed.
- Cross-link the dual-mode note into dig-rpc.md's public-read-tier tip and
  add a Related link + conformance/tier-map notes in peer-network.md.

Minor bump (additive normative spec content, no removed/renumbered
sections).
@MichaelTaylor3d MichaelTaylor3d merged commit d6498ff into main Jul 4, 2026
4 checks passed
@MichaelTaylor3d MichaelTaylor3d deleted the docs/dual-transport-rpc-18 branch July 4, 2026 15:11
MichaelTaylor3d added a commit that referenced this pull request Jul 10, 2026
…, support, role-based sidebar)

Implements ROADMAP Wave-1 docs items #1, #10, #30, #32.

#1 — Fix the 10-vs-100 DIG cost conflict (trust-critical). The canonical
ecosystem price is a flat 100 DIG per capsule (mint OR commit), matching
SYSTEM.md. Corrected the three places that wrongly said `commit` = 10 DIG:
  - onchain-anchoring.md: the Costs table + the "Cost and safety" bullets
  - command-reference.md: the on-chain banner + the `commit` row
Added a "why the price is flat" explainer (fixed-size capsule → uniform price)
and an "iterate for free, pay only to publish" callout.

#10 — Web-first, zero-cost quickstart. New docs/quickstart.md front door:
free draft/preview FIRST (no wallet), fund + publish (100 DIG) only at the
end; parallel CLI track (new/dev marked coming-soon, init/commit/deploy real).
Retitled the old CLI quickstart to "CLI tutorial" and cross-linked the two.

#30 — Support + error codes. New docs/support/: troubleshooting.md, faq.md,
consolidated error-codes.md (dig RPC -32xxx + CLI exit codes 0–16 from
digstore-cli/src/error.rs + DIGHub codes from hub apps/web/lib/errors.js:
API_CODE_MESSAGES + DIG_INSUFFICIENT/SLUG_TAKEN/WALLET_DECLINED/…), get-help.md.
Added "Get help" + Discord to the navbar and a Community section to the footer
(+ discord.svg icon).

#32 — Role-based sidebar + canonical glossary. sidebars.ts now groups docs into
tracks: Start here / Build dapps / Deploy & host / Support / Protocol (kept at
position 90, low-prominence). concepts.md remains the single canonical glossary,
aligned with SYSTEM.md; cross-linked from intro, quickstart, and support.

Maintained agent-friendly conventions (frontmatter keywords/tags + "## Related"
on every new/edited page); regenerated static/knowledge-graph.json via the
prebuild script (51 nodes, 367 edges) and updated static/llms.txt. Applied
ecosystem vocab (DIG not $DIG, DIGHub, ↗ for external links). `npm run build`
green (onBrokenLinks: throw); typecheck clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GjQgGAisBupqs7vpkmUhuN
MichaelTaylor3d added a commit that referenced this pull request Jul 10, 2026
… read certs (#10)

The peer-network spec already had the two RPC tiers (mTLS peer/control vs
anonymous public-read) but treated rpc.dig.net as purely the anonymous
front. Node-class clients (digstore CLI, dig-sdk, any DIG-identity-key
holder) must never downgrade to that anonymous path, even at the public
gateway, per the client->node connection order contract.

- New peer-network.md §0a: rpc.dig.net is dual-mode — an mTLS front
  (CERT_REQUIRED) for node-class-client identity certs, reached at all
  three ladder tiers (dig.local/localhost/rpc.dig.net), alongside the
  existing plain-HTTPS+CORS front for browsers.
- Ephemeral self-signed client certificate flow: an anonymous reader may
  use the mTLS front for channel-bound request integrity without any
  persisted identity or reputation, binding a signed request to its TLS
  session.
- Design-status note: implementations gate on the gateway mTLS endpoint's
  existence and must not hard-break before it is deployed.
- Cross-link the dual-mode note into dig-rpc.md's public-read-tier tip and
  add a Related link + conformance/tier-map notes in peer-network.md.

Minor bump (additive normative spec content, no removed/renumbered
sections).

Co-Authored-By: Claude <noreply@anthropic.com>
MichaelTaylor3d added a commit that referenced this pull request Jul 10, 2026
…, support, role-based sidebar)

Implements ROADMAP Wave-1 docs items #1, #10, #30, #32.

#1 — Fix the 10-vs-100 DIG cost conflict (trust-critical). The canonical
ecosystem price is a flat 100 DIG per capsule (mint OR commit), matching
SYSTEM.md. Corrected the three places that wrongly said `commit` = 10 DIG:
  - onchain-anchoring.md: the Costs table + the "Cost and safety" bullets
  - command-reference.md: the on-chain banner + the `commit` row
Added a "why the price is flat" explainer (fixed-size capsule → uniform price)
and an "iterate for free, pay only to publish" callout.

#10 — Web-first, zero-cost quickstart. New docs/quickstart.md front door:
free draft/preview FIRST (no wallet), fund + publish (100 DIG) only at the
end; parallel CLI track (new/dev marked coming-soon, init/commit/deploy real).
Retitled the old CLI quickstart to "CLI tutorial" and cross-linked the two.

#30 — Support + error codes. New docs/support/: troubleshooting.md, faq.md,
consolidated error-codes.md (dig RPC -32xxx + CLI exit codes 0–16 from
digstore-cli/src/error.rs + DIGHub codes from hub apps/web/lib/errors.js:
API_CODE_MESSAGES + DIG_INSUFFICIENT/SLUG_TAKEN/WALLET_DECLINED/…), get-help.md.
Added "Get help" + Discord to the navbar and a Community section to the footer
(+ discord.svg icon).

#32 — Role-based sidebar + canonical glossary. sidebars.ts now groups docs into
tracks: Start here / Build dapps / Deploy & host / Support / Protocol (kept at
position 90, low-prominence). concepts.md remains the single canonical glossary,
aligned with SYSTEM.md; cross-linked from intro, quickstart, and support.

Maintained agent-friendly conventions (frontmatter keywords/tags + "## Related"
on every new/edited page); regenerated static/knowledge-graph.json via the
prebuild script (51 nodes, 367 edges) and updated static/llms.txt. Applied
ecosystem vocab (DIG not $DIG, DIGHub, ↗ for external links). `npm run build`
green (onBrokenLinks: throw); typecheck clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GjQgGAisBupqs7vpkmUhuN
MichaelTaylor3d added a commit that referenced this pull request Jul 10, 2026
… read certs (#10)

The peer-network spec already had the two RPC tiers (mTLS peer/control vs
anonymous public-read) but treated rpc.dig.net as purely the anonymous
front. Node-class clients (digstore CLI, dig-sdk, any DIG-identity-key
holder) must never downgrade to that anonymous path, even at the public
gateway, per the client->node connection order contract.

- New peer-network.md §0a: rpc.dig.net is dual-mode — an mTLS front
  (CERT_REQUIRED) for node-class-client identity certs, reached at all
  three ladder tiers (dig.local/localhost/rpc.dig.net), alongside the
  existing plain-HTTPS+CORS front for browsers.
- Ephemeral self-signed client certificate flow: an anonymous reader may
  use the mTLS front for channel-bound request integrity without any
  persisted identity or reputation, binding a signed request to its TLS
  session.
- Design-status note: implementations gate on the gateway mTLS endpoint's
  existence and must not hard-break before it is deployed.
- Cross-link the dual-mode note into dig-rpc.md's public-read-tier tip and
  add a Related link + conformance/tier-map notes in peer-network.md.

Minor bump (additive normative spec content, no removed/renumbered
sections).

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant